Release notes

2024r7

Introduction of publication API

In a previous version, the option Mark as published was added to publication systems as an additional way of publishing publication records. Using this option, the publishing happens outside the Mediagenix applications.

For this, the publication API has been introduced. It will enable an external system to check for new or updated publication snapshots and send a response back to Mediagenix.

Note that the API is created with the API framework 2.0 so it might behave or look differently. For example, PUT calls are now called PATCH calls, the URLs are written in kebab case (meaning words are separated by dashes) and search calls have more attributes in the response.

It contains the following calls.

GET /publication-systems

This call enables the external system to search for the available publication systems, which can be used in the GET /publication-systems call.

The following parameters can be added to the URL of the call:

  • sort:
    This allows users to sort the publication systems in the response on

    • publicationSystemId: The external reference of the publication system.

    • name: The Name of the publication system.

    • kind: The Publication system kind, which has the predefined values press (Linear) or onlinePublication (On demand).

  • filter:
    This allows users to filter out publication systems with a certain publicationSystemId, name or kind.

  • limit:
    This allows users to define the number of results that are returned. By default, this is 25 in the new framework.

  • offset:
    This allows users to define the number of results that are omitted.

Note that if no parameters are included, all active publication systems are returned.

An example of the URL: /publication-systems?filter=eq(kind,onlinePublication)&sort=name

The call returns the publication systems as an array with its publicationSystemId, kind and name. It also has some additional attributes because of the new framework:

  • limit: The number of objects that would have been returned if all objects could be returned without taking any browsing permissions into account.

  • numberOfObjectsOmitted: The number of entries that were omitted due to browsing permissions.

  • offset: The number of returned entries skipped. For example, offset = 50 means the first 50 entries were skipped.

  • totalNumberOfObjects: The total number of objects that met the search conditions without taking the offset and limit parameters into account.

An example of the response:

{
    "data": [
        {
            "publicationSystemId": "243384000",
            "kind": "onlinePublication",
            "name": "Netflix"
        },
        {
            "publicationSystemId": "245960000",
            "kind": "onlinePublication",
            "name": "Telenet"
        },
        {
            "publicationSystemId": "4157336000",
            "kind": "onlinePublication",
            "name": "OldVOD"
        },
        {
            "publicationSystemId": "6249506000",
            "kind": "onlinePublication",
            "name": "Disney+"
        }
    ],
    "limit": 4,
    "numberOfObjectsOmitted": 0,
    "offset": 0,
    "totalNumberOfObjects": 4
}

GET /publication-snapshots

This call enables the external system to search for publication snapshots that need to be processed, so they can retrieve their id and use the GET /publication-snapshots/{publicationSnapshotId} call to retrieve its details.

The following parameters can be added to the URL of the call:

  • sort:
    This allows users to sort the publication systems in the response on

    • lastPubishedOn: The date on which the snapshot was created. Every time a record is published, a new snapshot is created, meaning the record was last published at the time the latest snapshot was created.

    • publicationSystem: The external reference of the publication system.

    • By default, the response is sorted by publicationSystem and lastPubishedOn in descending order, meaning the most recently published one is at the top.

  • filter:
    This allows users to filter out publication systems using lastPubishedOn, publicationSystemId and contentId, which is the external reference of the content of the snapshot.

  • limit:
    This allows users to define the number of results that are returned.

  • offset:
    This allows users to define the number of results that are omitted.

An example of the URL: /publication-snapshots?filter=eq(publicationSystemId,245960000)&sort=lastPublishedOn

The call returns all publication snapshots matching the filter parameter and their attributes. Note that, even if no parameters are included, only the most recent publication snapshot of publication records with the status Published are returned. For example, if the record was published three times, only the last one is returned. This also means snapshots of publication records with a status other than that, for example, New, New input after approval, Deleted, are ignored.

An example of the response:

{
   "data":[
{
    "publicationSnapshotId": "9500901220",
    "announcedTime": null,
    "aspectRatio": null,
    "brand": "TestWOnNet3",
    "cast": "Robert Downey Jr.",
    "communicateAsPremiereToPress": false,
    "contentCollectionDisplayNumber": null,
    "contentCollectionOrderNumber": null,
    "contentCollectionPosition": null,
    "contentId": "143048527",
    "datePreviousTransmission": null,
    "distributorNumber": null,
    "distributorReference": null,
    "endTime": "02:43:00.000",
    "EPGSeriesLinkId": null,
    "episodeNumbers": null,
    "episodeTitle": "NL",
    "extendedCast": "Robert Downey Jr.",
    "finalProductionYear": null,
    "hasAudioDescription": false,
    "hasClosedCaptions": false,
    "images": [
        {
            "imageId": "image",
            "highResolutionURL": "https://www.google.com/url?sa=i&url=https%3A%2F%2Fwww.imdb.com%2Ftitle%2Ftt4154796%2F&psig=AOvVaw0ScN-fD5ZAk281UO3jlett&ust=1676973978538000&source=images&cd=vfe&ved=0CBAQjRxqFwoTCIjOvIXto_0CFQAAAAAdAAAAABAE",
            "identification": "EN",
            "type": null
        }
    ],
    "internalEpisodeNumber": null,
    "isLive": false,
    "isRepeat": false,
    "isRerun": false,
    "languageComponents": [],
    "lastPublishedOn": "2024-06-04T14:11:59+01:00",
    "longDescriptionPrintedPress": "NL",
    "longDescriptionPrintedPressForSeries": null,
    "materialAspectRatio": null,
    "materialVideoFormat": null,
    "mediaAssetLabel": "ENC_0000001329",
    "parentalRating": "12",
    "parentSeriesTitle": null,
    "planningCategories": [],
    "pressStatus": "TestWOnPressStatus2",
    "pressTarget": "Dutch",
    "producers": null,
    "productCode": "MCU3-",
    "productionRegions": [
        "TestRegion1",
        "TestRegion3"
    ],
    "productionYear": 2019,
    "publicationEndDate": "2024-06-07",
    "publicationEndTime": null,
    "publicationStartDate": "2024-06-01",
    "punchline1": "NL",
    "punchline1ForSeries": null,
    "remarks": null,
    "response": null,
    "runningYear": "NL",
    "shortDescriptionPrintedPress": "NL",
    "shortDescriptionPrintedPressForSeries": null,
    "shortTeletextDescription": "NL",
    "shortTeletextDescriptionForSeries": null,
    "sound": null,
    "startTime": "00:00:00.000",
    "subtitlingCode": null,
    "title": "AVENGERS: ENDGAME",
    "translatedEpisodeTitle": "NL",
    "translatedTitle": "AVENGERS: ENDGAME",
    "transmissionId": "9500643922",
    "videoComponent": "6586350000",
    "videoFormat": null
}
   ],
   "totalNumberOfObjects": 1,
   "offset":0,
   "limit":0,
   "totalNumberOfObjects": 1
}

GET /publication-snapshots/{publicationSnapshotId}

This call enables the external system to retrieve the details of a specific publication snapshot. This means the publicationSnapshotId, i.e. external reference of the publication snapshot, has to be included in the URL.

The response returns the properties of the publication snapshot, including the recent remarks and response fields.

An example of the response:

{
    "publicationSnapshotId": "9500901220",
    "announcedTime": null,
    "aspectRatio": null,
    "brand": "TestWOnNet3",
    "cast": "Robert Downey Jr.",
    "communicateAsPremiereToPress": false,
    "contentCollectionDisplayNumber": null,
    "contentCollectionOrderNumber": null,
    "contentCollectionPosition": null,
    "contentId": "143048527",
    "datePreviousTransmission": null,
    "distributorNumber": null,
    "distributorReference": null,
    "endTime": "02:43:00.000",
    "EPGSeriesLinkId": null,
    "episodeNumbers": null,
    "episodeTitle": "NL",
    "extendedCast": "Robert Downey Jr.",
    "finalProductionYear": null,
    "hasAudioDescription": false,
    "hasClosedCaptions": false,
    "images": [
        {
            "imageId": "image",
            "highResolutionURL": "https://www.google.com/url?sa=i&url=https%3A%2F%2Fwww.imdb.com%2Ftitle%2Ftt4154796%2F&psig=AOvVaw0ScN-fD5ZAk281UO3jlett&ust=1676973978538000&source=images&cd=vfe&ved=0CBAQjRxqFwoTCIjOvIXto_0CFQAAAAAdAAAAABAE",
            "identification": "EN",
            "type": null
        }
    ],
    "internalEpisodeNumber": null,
    "isLive": false,
    "isRepeat": false,
    "isRerun": false,
    "languageComponents": [],
    "lastPublishedOn": "2024-06-04T14:11:59+01:00",
    "longDescriptionPrintedPress": "NL",
    "longDescriptionPrintedPressForSeries": null,
    "materialAspectRatio": null,
    "materialVideoFormat": null,
    "mediaAssetLabel": "ENC_0000001329",
    "parentalRating": "12",
    "parentSeriesTitle": null,
    "planningCategories": [],
    "pressStatus": "TestWOnPressStatus2",
    "pressTarget": "Dutch",
    "producers": null,
    "productCode": "MCU3-",
    "productionRegions": [
        "TestRegion1",
        "TestRegion3"
    ],
    "productionYear": 2019,
    "publicationEndDate": "2024-06-07",
    "publicationEndTime": null,
    "publicationStartDate": "2024-06-01",
    "punchline1": "NL",
    "punchline1ForSeries": null,
    "remarks": null,
    "response": null,
    "runningYear": "NL",
    "shortDescriptionPrintedPress": "NL",
    "shortDescriptionPrintedPressForSeries": null,
    "shortTeletextDescription": "NL",
    "shortTeletextDescriptionForSeries": null,
    "sound": null,
    "startTime": "00:00:00.000",
    "subtitlingCode": null,
    "title": "AVENGERS: ENDGAME",
    "translatedEpisodeTitle": "NL",
    "translatedTitle": "AVENGERS: ENDGAME",
    "transmissionId": "9500643922",
    "videoComponent": "6586350000",
    "videoFormat": null
}

More information on each attribute can be found in the YAML or on the API explorer.

PATCH /publication-snapshots/{publicationSnapshotId}

This call allows the external system to update the publication snapshot with a response and remarks after retrieving its details.

The publicationSnapshotId or external reference of the snapshot is mandatory in the URL.

The body contains the following attributes:

An example of the body:

{
  "response": "Received",
  "remarks": "OK 04-06-2024"
}

When the call is sent, the values are entered in the respective fields.

GET /publication-system-responses

This call can be used to retrieve the values of the PGPublicationSystemResponse drop-down list. These values are used for the response attribute in the PATCH /publication-snapshots call.

An example of the response:

[
    {
        "id": "Received",
        "name": "Received"
    },
    {
        "id": "Error",
        "name": "Error"
    }
]

The YAML has been added for this API. The latest version can be retrieved by using the GET /api call.